Repository navigation
Bring resources/DESIGN.md under its 40 KiB budget and retire its ceiling - #4290
Merged
Merged
Conversation
#4250 left resources/DESIGN.md at 45,886 bytes, 3 over its 45,883-byte ceiling. Under --base, check-design-docs.mjs holds any change to an over-ceiling file to 60% of that ceiling (27,529 bytes), which is under the 40,960-byte budget, so --update-ceilings drops the file's entry. Rewrite all 73 notes tersely down to 27,497 bytes. Every heading (and so every anchor the root index links), every issue reference and every named test is kept; bold invariants, gaps and residual risks stay, and mechanism detail the named tests pin is dropped per the root DESIGN.md rule. Dispatch-Task: harper-design-doc-ceiling-resources Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Restore the qualifications the review found missing: collection positions and the single-record resume exception, the includeSuperseded startTime exception, expiry hiding only without a source get, the cached getEntry options literal, TableResourceClass, syncWal-conditional floor sync, source- versus request-level noCacheStore, the static-mode array PUT gap, residency stubs, LMDB close completion and coercion's pattern-text exception. Fund them by writing harper refs as #N and tighter wording; the file is 27,500 bytes. Dispatch-Task: harper-design-doc-ceiling-resources Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…hree test pointers Dispatch-Task: harper-design-doc-ceiling-resources Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
⊙ Problem
npm run check:design-docsfails onmain:resources/DESIGN.mdis 45,886 bytes, 3 over its 45,883-byte ceiling since Clear a removed table TTL everywhere…. Any edit to an over-ceiling file must cut it to 60% of the ceiling, 27,529 bytes. A 3-byte trim fails.💡 Solution
Shorten all 73 notes to 27,485 bytes. That is under the 40 KiB budget, so
--update-ceilingsdrops the file's ceiling entry. Every heading (and anchor linked by the root index), every issue reference and all 101 named tests stay. Bold invariants stay, as do most gaps and residual risks; the ones the cut lost are listed in the issue below. Mechanism details covered by the named tests are dropped, per the rootDESIGN.mdrule for enforced invariants.🤔 Restore the dropped detail here?
No: it cannot fit under 27,529 bytes. Each dropped rule is listed in resources/DESIGN.md: decide which rules the 60% trim dropped to restore; after this merges the file has only the 40 KiB budget, so a follow-up can restore the ones worth their bytes.
⚖️ Alternatives
🤔 Move whole clusters into sibling notes instead?
No. It would keep every sentence, but a new note must be registered in the root
DESIGN.md. That file is 2 bytes under its own ceiling, so the edit would force the same 60% cut there. Reversible: a later PR can split notes out once the root index has room.🔧 Changes
resources/DESIGN.md: every note rewritten; focus on the residual-risk and gap clauses, since the review found overly broad claims there. Harper references are written#N, as the header now says;harper-pro#Nstays explicit.build-tools/design-docs-ceilings.json: only theresources/DESIGN.mdentry is removed.✅ Verification
npm run check:design-docsandnpm run check:design-docs -- --base origin/main(CI's pull-request form) pass.npx prettier --checkon both files,npm run lint(oxlint) andnpm run check:unit-partitionpass.PR QA: skipped @ 1c840fc — not substantive (design-note trim, no runtime change).
Docs: none needed (internal design note).
Signed: Claude Opus 5.5
🤖 Generated with Claude Code
Release target: main — fixes a design-doc check that is red on main
Related PRs: #3651 overlaps (edits notes this rewrites; whichever lands second re-fits its text), #4265 overlaps (changes the design-docs ceiling check), 5 others independent
Complexity: medium
Deferred findings
fad0ad9f7657598eminor documentation —resources/DESIGN.md— blob cleanup per-round reset, confirmation fallback, retained-file rules dropped — filed resources/DESIGN.md: decide which rules the 60% trim dropped to restore #42895ba1e73702599eacminor documentation —resources/DESIGN.md— false-mode search snapshot ordering and default-get no-promise rule dropped — filed resources/DESIGN.md: decide which rules the 60% trim dropped to restore #4289ca7966c34b67bde7minor documentation —resources/DESIGN.md— precedesAudited tie scope and ref-walk distinctions compressed — filed resources/DESIGN.md: decide which rules the 60% trim dropped to restore #428923ca2dc6f5e8c5c4minor documentation —resources/DESIGN.md— joinable-scope detachWrite holder and LMDB restrictions dropped — filed resources/DESIGN.md: decide which rules the 60% trim dropped to restore #42896747cf7b6058af91minor documentation —resources/DESIGN.md— PK record filter must agree with id filter dropped — filed resources/DESIGN.md: decide which rules the 60% trim dropped to restore #4289dd7678e64ff80a4bminor documentation —resources/DESIGN.md— sharding quarantine/replay boundary and blobReferenceGeneration ordering dropped — filed resources/DESIGN.md: decide which rules the 60% trim dropped to restore #4289c3bf19027c0e2fd7minor documentation —resources/DESIGN.md— read-only post exemption, delete staging, strip audit-off, checkpoint epoch, untimed-drop rules dropped — filed resources/DESIGN.md: decide which rules the 60% trim dropped to restore #4289c281444ef5b68939minor documentation —resources/DESIGN.md— full-text fullTextFields, assertFullTextWrite, capture-order failure dropped — filed resources/DESIGN.md: decide which rules the 60% trim dropped to restore #42895a6fdf4ff44935e9minor documentation —resources/DESIGN.md— over-time monitor conflict deadline, timeoutBudget, phantom resolution dropped — filed resources/DESIGN.md: decide which rules the 60% trim dropped to restore #4289eb963850520ecb5fminor documentation —resources/DESIGN.md— same-thread registry threadStartBound qualification omitted — filed resources/DESIGN.md: decide which rules the 60% trim dropped to restore #4289Origin — the dispatch brief this PR was written from
Bring resources/DESIGN.md back under its size ceiling so runLinter passes on main
runLinter/npm run check:design-docsfails on harper main: resources/DESIGN.md is 45,886 bytes, 3 over its ceiling of 45,883 (over since harper#4250). Bring it under its ceiling the way harper#4280 did for security/DESIGN.md and harper#4228 for config/DESIGN.md: trim narration, duplicates and anything the code already says, keep every invariant, residual risk, issue reference, heading anchor and named test pointer. The check requires a substantial cut once a file is over (harper#4280 cut to under 60% to retire the ceiling); follow whatevercheck-design-docs.mjsrequires, and retire or lower its ceilings entry withnpm run check:design-docs -- --update-ceilingsas #4280 did. Do not raise the ceiling.Coordinate: draft harper#4265 ("Hold a design-docs ceilings change only to the files whose entry it changes") touches the same check; don't change the checker here. Other open PRs edit resources/DESIGN.md (harper#3504's task may add a note); keep this PR to the trim so it rebases easily. Run check:design-docs, lint, prettier. Open a PR listing what was cut.
Acceptance
check:design-docs and runLinter pass on the branch; no invariant removed (PR body lists cuts); ceiling not raised.
Dispatch: task
harper-design-doc-ceiling-resources· queued by kris-session · ran by claude/opus/high · worker kzyp-xps-1Ready-For-Promotion: 1c840fc urgency=fast late=folded
Review-Coverage: authored=claude; ran=cursor-composer,gemini,codex,cursor-grok; late=cursor-grok:adjudicated; adjudicated=domain; declined=muse; urgency=fast; rounds=5; full=1 @ 1c840fc
Review-Attention: read ~3m (decisions: restore-in-follow-up, pointer-for-prose-funding) @ 1c840fc